<?php

/**
 * Query result class for the DB_Simplex package 
 *
 * PHP version 5
 *
 * Simplex is now a defunct database format, so this package only supports
 * reading of database to recover data.
 *
 * @category  Database
 * @package   DB_Simplex
 * @author    Philippe Jausions <jausions@php.net>
 * @copyright 2008 by 11abacus / Philippe Jausions
 * @license   http://www.opensources.org/licenses/bsd-license.php BSD license
 * @version   CVS: $Id: $
 * @link      http://pear.11abacus.com/package/DB_Simplex
 */

require_once 'PEAR/Exception.php';

/**
 * Query result class for DB_Simplex package
 *
 * @category  Database
 * @package   DB_Simplex
 * @author    Philippe Jausions <jausions@php.net>
 * @copyright 2008 by 11abacus / Philippe Jausions
 * @license   http://www.opensources.org/licenses/bsd-license.php BSD license
 * @version   Release: @package_version@
 * @link      http://pear.11abacus.com/package/DB_Simplex
 */
class DB_Simplex_Result implements Countable
{
    /**
     * Data read from the data file
     *
     * @var array
     */
    protected $data;

    /**
     * List of fields read on the data file 
     *
     * Index represent the index in the $data member. The value is an array
     * with the following indexes:
     * <ul>
     *  <li>Table: table the field belongs to</li>
     *  <li>Name: field name</li>
     *  <li>Length: length of the field</li>
     *  <li>Comment</li>
     *  <li>Default</li>
     *  <li>Required</li>
     * </ul>
     * 
     * @var array
     */
    protected $fieldsRead;

    /**
     * List of fields in the SELECT statemetn
     *
     * The array is a list of fields selected, defined by an array with the
     * following indexes:
     * <ul>
     *  <li>0: table name</li>
     *  <li>1: field name</li>
     *  <li>2: field name alias (for associative array index in the result)</li> 
     *  <li>3: index in $data</li>
     * </ul> 
     * 
     * @var array
     */
    protected $fieldsSelected;

    /**
     * Class constructor
     *
     * @param array $data           Data read from the database
     * @param array $fieldsRead     List of field read
     * @param array $fieldsSelected List of fields in the SELECT
     */
    public function __construct($data, $fieldsRead, $fieldsSelected)
    {
        $this->data           = $data;
        $this->fieldsRead     = $fieldsRead;
        $this->fieldsSelected = $fieldsSelected;
    }

    /**
     * Returns the row count in data retrieved
     *
     * @return integer Row count or NULL if result was freed
     */
    public function count()
    {
        return ($this->data === null) ? null : count($this->data);
    }
    
    /**
     * Returns how many columns were selected
     *
     * @return integer Columns count or NULL if result was freed
     */
    public function countColumns()
    {
        return ($this->fieldsSelected === null) 
               ? null : count($this->fieldsSelected);
    }
    
    /**
     * Returns the name of the given column in the result
     *
     * @param integer $col column number
     * 
     * @return string Column name
     */
    public function getColumnName($col)
    {
        if (!isset($this->fieldsSelected[$col])) {
            throw new DB_Simplex_Exception_NoSuchField('No such column "'.$col
                    .'" in result');
        }
        return $this->fieldsSelected[$col][2];
    }
    
    /**
     * Returns a list of columns names in the result
     *
     * @return array List of column names or NULL if result was freed
     */
    public function getColumnNames()
    {
        if ($this->fieldsSelected === null) {
            return null;
        }
        $cols = array();
        foreach ($this->fieldsSelected as $field) {
            $cols[] = $field[2];
        }
        return $cols;
    }
    
    /**
     * Frees the data
     * 
     * @return void
     */
    public function free()
    {
        $this->data           = null;
        $this->fieldsSelected = null;
        $this->fieldsRead     = null;
    }
}

?>